/*
 * Copyright 2012-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.web.server;

/**
 * 表示一个完全配置好的 Web 服务器的简单接口（例如 Tomcat、Jetty、Netty）。
 * 允许服务器被 {@link #start() 启动} 和 {@link #stop() 停止}。
 *
 * @author Phillip Webb
 * @author Dave Syer
 * @since 2.0.0
 */
public interface WebServer {

	/**
	 * 启动 Web 服务器。
	 * 如果服务器已经启动，调用此方法不会有任何效果。
	 * @throws WebServerException 如果服务器无法启动，则抛出异常
	 */
	void start() throws WebServerException;

	/**
	 * 停止 Web 服务器。
	 * 如果服务器已经停止，调用此方法不会有任何效果。
	 * @throws WebServerException 如果服务器无法停止，则抛出异常
	 */
	void stop() throws WebServerException;

	/**
	 * 返回服务器监听的端口号。
	 * @return 端口号（如果未监听任何端口则返回 -1）
	 */
	int getPort();

	/**
	 * 发起 Web 服务器的优雅关闭。
	 * 阻止新的请求处理，并在关闭尝试结束时调用给定的 {@code callback}。
	 * 关闭尝试可以通过调用 {@link #stop} 显式结束。
	 * 默认实现会立即调用回调，状态为 {@link GracefulShutdownResult#IMMEDIATE}，
	 * 即不做优雅关闭尝试。
	 * @param callback 优雅关闭完成时调用的回调
	 * @since 2.3.0
	 */
	default void shutDownGracefully(GracefulShutdownCallback callback) {
		callback.shutdownComplete(GracefulShutdownResult.IMMEDIATE);
	}

}
